<h1>PlaceObject2</h1>

<p>PlaceObject2 is an instruction to the Flash Player to add and manipulate 
objects (shapes, buttons, etc.) on its display list. It supercedes PlaceObject 
providing more functionality and easier manipulation of  objects in the display 
list through the following operations:</p>

<div style="padding-left:20px; margin-bottom:10px;">
<ul>
<li>Place a new shape on the display list.</li>
<li>Change an existing shape by moving it to new location or changing its appearance.</li>
<li>Replace an existing shape with a another.</li>
<li>Define clipping layers to mask objects displayed in front of a shape.</li>
<li>Control the morphing process that changes one shape into another.</li>
<li>Assign names to objects rather than using their identifiers.</li>
<li>Define the sequence of actions that are executed when an event occurs in movie clip.</li>
</ul>
</div>

<p>The encoded PlaceObject2 instruction contains a series of bit fields that 
indicate whether optional fields and objects are also encoded reducing the 
number of bytes required to encode the object when defining simple display list 
operations.</p>

<table>

<tr>
<th nowrap>Field Name</th>
<th>Type</th>
<th>Size</th>
<th>Description</th>
</tr>

<tr>
<td nowrap valign="top">type</td>
<td nowrap valign="top">unsigned bit</td>
<td nowrap valign="top" align="right">10</td>
<td>Identifies the PlaceObject2 instruction when it is encoded. It is encoded 
with the length field as a 16-bit integer (Little-endian byte order).</td>
</tr>

<tr>
<td nowrap valign="top">length</td>
<td nowrap valign="top">unsigned bit</td>
<td nowrap valign="top" align="right">6</td>
<td>The length in bytes of the body of the instruction when it is encoded. If 
the length is greater than 62 then this field is set to 0x3F and the length is 
encoded using the extendedLength field. Encoded with the type field as a 16-bit 
integer.</td>
</tr>

<tr>
<td nowrap valign="top">extendedLength</td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">32</td>
<td>Optional. Contains the length in bytes of the encoded instruction if it is
greater than 62 bytes. If the length is 62 bytes or less then this field is 
omitted.</td>
</tr>

<tr>
<td nowrap valign="top">hasClipEvents</td>
<td nowrap valign="top">boolean</td>
<td nowrap valign="top" align="right">1</td>
<td>Set if ClipEvents are included.</td>
</tr>

<tr>
<td nowrap valign="top">hasClippingDepth</td>
<td nowrap valign="top">boolean</td>
<td nowrap valign="top" align="right">1</td>
<td>Set if a Clipping Depth is defined.</td>
</tr>

<tr>
<td nowrap valign="top">hasName</td>
<td nowrap valign="top">boolean</td>
<td nowrap valign="top" align="right">1</td>
<td>Set if a movie clip name is included.</td>
</tr>

<tr>
<td nowrap valign="top">hasRatio</td>
<td nowrap valign="top">boolean</td>
<td nowrap valign="top" align="right">1</td>
<td>Set if a morhping ratio is defined.</td>
</tr>

<tr>
<td nowrap valign="top">hasColorTransform</td>
<td nowrap valign="top">boolean</td>
<td nowrap valign="top" align="right">1</td>
<td>Set if a colour transform is defined.</td>
</tr>

<tr>
<td nowrap valign="top">hasTransform</td>
<td nowrap valign="top">boolean</td>
<td nowrap valign="top" align="right">1</td>
<td>Set if a coordinate transform is defined.</td>
</tr>

<tr>
<td nowrap valign="top">placeType</td>
<td nowrap valign="top">unsigned bit</td>
<td nowrap valign="top" align="right">2</td>
<td>Indicates whether a new object is being placed in the display list or an 
existing object is being modified or replaced.</td>
</tr>

<tr>
<td nowrap valign="top">identifier</td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16</td>
<td>The identifier of the object to added to the display list.</td>
</tr>

<tr>
<td nowrap valign="top">layer</td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16</td>
<td>Defines the order in which objects are displayed.</td>
</tr>

<tr>
<td nowrap valign="top">transform</td>
<td nowrap valign="top">CoordTransform</td>
<td nowrap valign="top" align="right">&nbsp;</td>
<td>Optional. A coordinate transform defines the position, scale and rotation of 
the object. It may be omitted, when updating an object, if its position on the 
screen does not change. It is required when placing an object on the display
list for the first time.</td>
</tr>

<tr>
<td nowrap valign="top">colorTransform</td>
<td nowrap valign="top">ColorTransform</td>
<td nowrap valign="top" align="right">&nbsp;</td>
<td>Optional. A colour transform defines any colour changes such as transparency 
effects. It may be omitted if the colour of an object (contained in the 
definition) is not changed.</td>
</tr>

<tr>
<td nowrap valign="top">depth</td>
<td nowrap valign="top">bit</td>
<td nowrap valign="top" align="right">10</td>
<td>Optional. With the introduction of Flash 3 the display list supported a 
clipping layer. This allows the outline of an object (typically a shape) to 
define a clipping path that is used to mask other objects placed in front of it. 
The depth identifies the layer number up to which objects will be clipped by 
this object's outline. If an object will not clip objects placed in front of it 
on the display list then this may be omitted.
</td>
</tr>

<tr>
<td nowrap valign="top">ratio</td>
<td nowrap valign="top">bit</td>
<td nowrap valign="top" align="right">10</td>
<td>Optional. DefineMorphShape defines a start and end shape. The Flash Player 
performs the interpolation that transforms one shape into another. The progress 
of the morphing process is controlled by the ratio which ranges from 0 to 65535, 
where 0 generates a shape identical to the starting shape in the 
DefineMorphShape object and 65535 generates the shape at the end of the morphing 
process.</td>
</tr>

<tr>
<td nowrap valign="top">name</td>
<td nowrap valign="top">bit</td>
<td nowrap valign="top" align="right">10</td>
<td>Optional. A name to assign to the object.</td>
</tr>

<tr>
<td nowrap valign="top">reserved</td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16</td>
<td>Optional. Always set to 0x0000. Marks the end of the encoded instruction if 
no ClipEvents are defined.</td>
</tr>

<tr>
<td nowrap valign="top">eventMask</td>
<td nowrap valign="top">unsigned bit</td>
<td nowrap valign="top" align="right">16 or 32</td>
<td>Optional. Contains the events from each ClipEvent bitwise or'ed. This allows 
the Flash Player to quickly identify the complete set of events that a movie clip 
will respond to. In Flash 5 this was a 16-bit field. The event model for movie clips
was extended in Flash 6 so the size of this fields changed to 32 bits.</td>
</tr>

<tr>
<td nowrap valign="top">clipEvents</td>
<td nowrap valign="top">ClipEvent</td>
<td nowrap valign="top" align="right">[n]</td>
<td>Optional. An array of n ClipEvents. Each ClipEvent defines the series of actions that
will be executed when a movie clip receives an event.</td>
</tr>

<tr>
<td nowrap valign="top">eventEnd</td>
<td nowrap valign="top">unsigned int</td>
<td nowrap valign="top" align="right">16 or 32</td>
<td>Optional. Always zero. Marks the end of the encoded ClipEvents. In Flash 5 this is a
16-bit field. From Flash 6 onwards it is 32 bits.</td>
</tr>

</table>

<p>Since only one object can be placed on a given layer an existing object on 
the display list can be identified by the layer it is displayed on rather than 
its identifier. Therefore Layer is the only required attribute. All the other 
attributes are optional - depending on the type of display list operation being 
performed.</p>


<h2>Movie Clip Events</h2>
<p>With the introduction of Flash 5, movie clips (defined using DefineMovieClip) 
could specify sequences of actions that would be performed in response to mouse 
or keyboard events. The actions are specified using ClipEvents and the PlaceObject2
instruction is used to register the actions in response to a particular event 
with the Flash player. Multiple events can be handled by defining an ClipEvent 
for each type of event.</p>

<h2>History</h2>
<p>The PlaceObject2 instruction is documented as the PlaceObject2 tag in the 
Macromedia Flash (SWF) File Format Specification. It was introduced in Flash 3. 
Support for ClipEvents was added in Flash 5.</p>
